Create a new reader group.

12 May 2026
10 Minutes to read
Contributors

Print
Share
Dark
Light

Create a new reader group.

Updated on 12 May 2026
10 Minutes to read
Contributors

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback!

Post

/v3/projects/{project_id}/readers/groups

Creates a new reader group with the specified title, description, associated readers, and access scope. The response includes a Location header pointing to the newly created group's detail endpoint. Associated readers and SSO users can be assigned at creation time. The access scope controls which project versions, categories, and languages the group members can access. Requires the UpdateRolesAccountsAndGroups permission. Returns 201 Created on success.

Security

OAuth

All V3 endpoints require a Bearer token. Generate tokens in the Document360 portal under Settings > API Tokens. Tokens are project-scoped, require the customerApi scope, and do not expire by default. Tokens can be revoked at any time from the portal. Include the token in every request: Authorization: Bearer <your-token>. Alternatively, use the Authorize button below to sign in via OAuth2 Authorization Code flow with PKCE.

FlowAuthorization Code

Authorization URLhttps://identity.document360.net/connect/authorize

Token URLhttps://identity.document360.net/connect/token

Scopes:

customerApiDocument360 Customer API

Path parameters

project_id

string (uuid) Required

The unique identifier of the project. Retrieve project IDs from GET /v3/projects.

Example9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d

Body parameters

Reader group creation details.

Create a reader group

Creates a new reader group with version-scoped access and two initial members.

{
  "title": "Beta Testers",
  "description": "Readers who have access to beta documentation.",
  "associated_readers": [
    "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
    "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b"
  ],
  "access_scope": {
    "access_level": "version",
    "categories": null,
    "project_versions": [
      "1c2d3e4f-5a6b-7c8d-9e0f-a1b2c3d4e5f6"
    ],
    "languages": null
  },
  "associated_invited_sso_users": null
}

Expand All

object

Request to create a new reader group.

title

string Required

Display name of the reader group. Maximum 50 characters.

Min length1

Max length50

ExampleBeta Testers

description

string | null

Description of the reader group's purpose.

associated_readers

Array of string | null

List of reader IDs to add to this group. Retrieve reader IDs from GET /v3/projects/{projectId}/readers.

string

access_scope

object Required

The access scope to apply to all readers in this group.

access_level

string

The level at which access is scoped. Possible values: 0 = None, 1 = Category, 2 = Version, 3 = Project, 4 = Language, 5 = Article, 6 = Workspace.

Valid values[ "none", "category", "version", "project", "language", "article", "workspace" ]

categories

Array of object (CategoryScope) | null

List of specific category scopes when AccessLevel is Category (1). Null or empty for broader access levels.

object

Specifies access to a specific category within a project version and language.

project_version_id

string | null

Unique identifier of the project version containing the category. Retrieve from GET /v3/projects/{projectId}/project-versions.

category_id

string | null

Unique identifier of the category to grant access to. Retrieve from GET /v3/projects/{projectId}/categories.

lang_code

string | null

Language code for the category translation (e.g., "en", "fr", "de"). Retrieve available languages from GET /v3/projects/{projectId}/languages.

Exampleen

project_versions

Array of string | null

List of project version IDs the reader has access to when AccessLevel is Version (2). Retrieve version IDs from GET /v3/projects/{projectId}/project-versions.

string

languages

Array of object (LanguageScope) | null

List of language scopes defining which translations the reader can access. Applicable when AccessLevel is Language (4).

object

Specifies access to a specific language within a project version.

project_version_id

string | null

Unique identifier of the project version. Retrieve from GET /v3/projects/{projectId}/project-versions.

lang_code

string | null

Language code to grant access to (e.g., "en", "fr", "de"). Retrieve available languages from GET /v3/projects/{projectId}/languages.

Exampleen

associated_invited_sso_users

Array of string | null

List of SSO invitation IDs to associate with this reader group. Applicable only for SSO readers who haven't logged in yet.

string

Responses

201

Reader group created successfully.

Headers

Location

string

URL of the newly created resource.

Newly created reader group

Returns the reader group that was just created

{
  "data": {
    "id": "a9b0c1d2-e3f4-4a5b-c6d7-e8f9a0b1c2d3",
    "title": "Partner Documentation",
    "description": "Reader group for integration partners with access to API docs",
    "associated_readers": [],
    "associated_invited_sso_users": [],
    "access_scope": {
      "access_level": "category",
      "categories": [
        {
          "project_version_id": "f7a8b9c0-d1e2-4f3a-b4c5-d6e7f8a9b0c1",
          "category_id": "d2e3f4a5-b6c7-4d8e-f9a0-b1c2d3e4f5a6",
          "lang_code": "en"
        }
      ],
      "project_versions": [],
      "languages": []
    }
  },
  "success": true,
  "request_id": "f6a7b8c9-d0e1-2345-fabc-d56789012345",
  "errors": [],
  "warnings": []
}

Expand All

object

Generic API response wrapper containing typed data.

data

object

Response data payload.

string (uuid) | null

Unique identifier of the reader group.

Example9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d

title

string | null

Display name of the reader group.

ExampleBeta Testers

description

string | null

Description of the reader group's purpose.

associated_readers

Array of string | null

List of reader IDs that belong to this group. Corresponds to readers from GET /v3/projects/{projectId}/readers.

string

associated_invited_sso_users

Array of string | null

List of SSO invitation IDs associated with this reader group. Applicable only for SSO readers who haven't logged in yet.

string

access_scope

object | null

The access scope applied to all readers in this group.

access_level

string

The level at which access is scoped. Possible values: 0 = None, 1 = Category, 2 = Version, 3 = Project, 4 = Language, 5 = Article, 6 = Workspace.

Valid values[ "none", "category", "version", "project", "language", "article", "workspace" ]

categories

Array of object (CategoryScope) | null

List of specific category scopes when AccessLevel is Category (1). Null or empty for broader access levels.

object

Specifies access to a specific category within a project version and language.

project_version_id

string | null

Unique identifier of the project version containing the category. Retrieve from GET /v3/projects/{projectId}/project-versions.

category_id

string | null

Unique identifier of the category to grant access to. Retrieve from GET /v3/projects/{projectId}/categories.

lang_code

string | null

Language code for the category translation (e.g., "en", "fr", "de"). Retrieve available languages from GET /v3/projects/{projectId}/languages.

Exampleen

project_versions

Array of string | null

List of project version IDs the reader has access to when AccessLevel is Version (2). Retrieve version IDs from GET /v3/projects/{projectId}/project-versions.

string

languages

Array of object (LanguageScope) | null

List of language scopes defining which translations the reader can access. Applicable when AccessLevel is Language (4).

object

Specifies access to a specific language within a project version.

project_version_id

string | null

Unique identifier of the project version. Retrieve from GET /v3/projects/{projectId}/project-versions.

lang_code

string | null

Language code to grant access to (e.g., "en", "fr", "de"). Retrieve available languages from GET /v3/projects/{projectId}/languages.

Exampleen

success

boolean

Whether the API request was successful.

request_id

string

Unique identifier for request tracing and correlation.

Min length1

errors

Array of object (ApiError) | null

List of errors if the request failed.

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

List of non-fatal warnings from the request.

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

400

The request body is malformed or contains invalid JSON.

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

401

Authentication token is missing or invalid.

Headers

WWW-Authenticate

string

Indicates the authentication scheme required. Returns `Bearer` with optional `error` and `error_description` parameters per RFC 6750.

Missing or invalid token

Authentication token is missing or invalid.

{
  "type": "https://developer.document360.com/errors/unauthorized",
  "title": "Unauthorized.",
  "status": 401,
  "detail": "The authentication token is missing or has expired.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "UNAUTHORIZED",
      "message": "Bearer token is missing or invalid.",
      "field": null,
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

422

Validation failed.

Validation failed

The request body contains invalid data.

{
  "type": "https://developer.document360.com/errors/validation-error",
  "title": "Unprocessable Entity.",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "This field is required.",
      "field": "title",
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

429

Rate limit exceeded. Retry after the duration specified in the Retry-After header.

Headers

Retry-After

integer

Number of seconds to wait before retrying the request. Use exponential backoff with jitter for optimal retry behavior.

X-RateLimit-Limit

integer

The maximum number of requests allowed in the current time window. Limits are applied per API token per project.

X-RateLimit-Remaining

integer

The number of requests remaining in the current time window. When this reaches 0, subsequent requests will receive a 429 response.

X-RateLimit-Reset

integer

The UTC epoch timestamp (in seconds) when the current rate limit window resets.

Rate limit exceeded

Rate limit exceeded.

{
  "type": "https://developer.document360.com/errors/too-many-requests",
  "title": "Too Many Requests.",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "TOO_MANY_REQUESTS",
      "message": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.",
      "field": null,
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

500

An unexpected server error occurred.

Unexpected server error

Unexpected server error.

{
  "type": "https://developer.document360.com/errors/internal-error",
  "title": "Internal Server Error.",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again or contact support.",
  "instance": null,
  "trace_id": "req_abc123def456",
  "errors": [
    {
      "code": "INTERNAL_SERVER_ERROR",
      "message": "An unexpected error occurred.",
      "field": null,
      "details": null
    }
  ],
  "warnings": null
}

Expand All

object

RFC 7807 Problem Details response for V3 API errors. Content-Type: application/problem+json

type

string

URI reference identifying the error type (links to documentation).

Min length1

title

string

Short human-readable summary of the error type.

Min length1

status

integer (int32)

HTTP status code.

detail

string | null

Human-readable explanation specific to this occurrence.

instance

string | null

URI of the request that generated the error.

trace_id

string | null

Request trace identifier for correlation.

errors

Array of object (ApiError) | null

Structured list of specific errors (extension field).

object

Represents an error returned by the API.

code

string

Machine-readable error code (e.g. VALIDATION_ERROR, RESOURCE_NOT_FOUND).

Min length1

message

string

Human-readable error message.

Min length1

field

string | null

The request field that caused the error, if applicable.

details

string | null

Additional context about the error.

warnings

Array of object (ApiWarning) | null

Non-fatal warnings (extension field).

object

Represents a non-fatal warning from the API.

code

string

Machine-readable warning code.

Min length1

message

string

Human-readable warning message.

Min length1

Was this article helpful?

What's Next

Get search analytics summary with total, successful, no-result, and bounced search counts.